5. Interfaces

5.1. Notification

See Notification for the technical details of this interface.

The subscription & notification process is managed by a middleware and is described in the following diagram:

!include "skin.iwsd" hide footbox participant "Emitter" as PR participant "Notification\nEngine" as N participant "Subscriber" as CR note over PR,N: First step is to create the topic PR -> N: create_topic(name) activate PR activate N N --> PR: uuid deactivate N deactivate PR note over N,CR: Then a system can subscribe for events published on that topic CR -> N: subscribe(topic,URL) activate CR activate N N --> CR: id deactivate CR deactivate N ... later ... note over N,CR: confirm the address before the subscription is active N -> CR: notify(token) activate N activate CR CR -> N: subscribe_CB(token) activate N #FFBBB N --> CR: ok deactivate N CR --> N: ok deactivate CR deactivate N note over PR,CR: it is now possible to publish notification PR -> N: publish(message) activate PR activate N N -> N: store N --> PR: ok deactivate PR ... loop subscriptions N -> CR: subscribe_CB(message) activate CR CR --> N: ok deactivate CR end deactivate N

Fig. 5.1 Subscription & Notification Process

5.1.1. Services

subscribe(topic, URL)

Subscribe a URL to receive notifications sent to one topic

Parameters:
  • topic (str) – Topic
  • URL (str) – URL to be called when a notification is available
Returns:

a subscription ID

This service is synchronous.

unsubscribe(id)

Unsubscribe a URL from the list of receiver for one topic

Parameters:id (str) – Subscription ID
Returns:bool

This service is synchronous.

confirm(token)

Confirm that the URL used during the subscription is valid

Parameters:token (str) – A token send through the URL.
Returns:bool

This service is synchronous.

publish(topic, subject, message)

Notify of a new event all systems that subscribed to this topic

Parameters:
  • topic (str) – Topic
  • subject (str) – The subject of the message
  • message (str) – The message itself (a string buffer)
Returns:

N/A

This service is asynchronous (systems that subscribed on this topic are notified asynchronously).

5.1.2. Dictionaries

As an example, below there is a list of events that each component might handle.

Table 5.1 Event Type
Event Type Emitted by CR Emitted by PR
Live birth ✔  
Death ✔  
Fœtal Death ✔  
Marriage ✔  
Divorce ✔  
Annulment ✔  
Separation, judicial ✔  
Adoption ✔  
Legitimation ✔  
Recognition ✔  
Change of name ✔  
Change of gender ✔  
New person   ✔
Duplicate person ✔ ✔

5.2. Data Access

See Data Access for the technical details of this interface.

5.2.1. Services

getPersonAttributes(UIN, names)

Retrieve person attributes.

Authorization: To be defined

Parameters:
  • UIN (str) – The person’s UIN
  • names (list[str]) – The names of the attributes requested
Returns:

a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from PR.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "PR" as PR note over CR,PR: CR can request person's attributes from PR CR -> PR: getPersonAttributes(UIN,[names]) PR -->> CR: attributes note over CR,PR: PR can request person's attributes from CR PR -> CR: getPersonAttributes(UIN,[names]) CR -->> PR: attributes

Fig. 5.2 getPersonAttributes Sequence Diagram

matchPersonAttributes(UIN, attributes)

Match person attributes. This service is used to check the value of attributes without exposing private data

Authorization: To be defined

Parameters:
  • UIN (str) – The person’s UIN
  • attributes (list[(str,str)]) – The attributes to match. Each attribute is described with its name and the expected value
Returns:

If all attributes match, a Yes is returned. If one attribute does not match, a No is returned along with a list of (name,reason) for each non-matching attribute.

This service is synchronous. It can be used to match attributes in CR or in PR.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "PR" as PR note over CR,PR: CR can match person's attributes in PR CR -> PR: matchPersonAttributes(UIN,[attributes]) PR -->> CR: Y/N+reasons note over CR,PR: PR can match person's attributes in CR PR -> CR: matchPersonAttributes(UIN,[attributes]) CR -->> PR: Y/N+reasons

Fig. 5.3 matchPersonAttributes Sequence Diagram

verifyPersonAttributes(UIN, expressions)

Evaluate expressions on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data

Authorization: To be defined

Parameters:
  • UIN (str) – The person’s UIN
  • expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=) and the attribute value
Returns:

A Yes if all expressions are true, a No if one expression is false, a Unknown if To be defined

This service is synchronous. It can be used to verify attributes in CR or in PR.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "PR" as PR note over CR,PR: CR can verify person's attributes in PR CR -> PR: verifyPersonAttributes(UIN,[expressions]) PR -->> CR: Y/N/U note over CR,PR: PR can verify person's attributes in CR PR -> CR: verifyPersonAttributes(UIN,[expressions]) CR -->> PR: Y/N/U

Fig. 5.4 verifyPersonAttributes Sequence Diagram

getPersonUIN(attributes)

Retrieve UIN based on a set of attributes. This service is used when the UIN is unknown.

Authorization: To be defined

Parameters:attributes (list[(str,str)]) – The attributes to be used to find UIN. Each attribute is described with its name and its value
Returns:a list of matching UIN

This service is synchronous. It can be used to get the UIN of a person.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "PR" as PR note over CR,PR: CR can get UIN from PR CR -> PR: getPersonUIN([attributes]) PR -->> CR: [UIN] note over CR,PR: PR can get UIN from CR PR -> CR: getPersonUIN([attributes]) CR -->> PR: [UIN]

Fig. 5.5 getPersonUIN Sequence Diagram

getDocument(UINs, documentType, format)

Retrieve in a selected format (PDF, image, …) a document such as a marriage certificate.

Authorization: To be defined

Parameters:
  • UIN (list[str]) – The list of UINs for the persons concerned by the document
  • documentType (str) – The type of document (birth certificate, etc.)
  • format (str) – The format of the returned/requested document
Returns:

The list of the requested documents

This service is synchronous. It can be used to get the documents for a person.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "PR" as PR note over CR,PR: CR can get a document from PR CR -> PR: getDocument([UIN],documentType,format) PR -->> CR: [documents] note over CR,PR: PR can get a document from CR PR -> CR: getDocument([UIN],documentType,format) CR -->> PR: [documents]

Fig. 5.6 getDocument Sequence Diagram

5.2.2. Dictionaries

As an example, below there is a list of attributes/documents that each component might handle.

Table 5.2 Person Attributes
Attribute Name In CR In PR Description
UIN ✔ ✔  
first name ✔ ✔  
last name ✔ ✔  
spouse name ✔ ✔  
date of birth ✔ ✔  
place of birth ✔ ✔  
gender ✔ ✔  
date of death ✔ ✔  
place of death ✔    
reason of death ✔    
status   ✔ Example: missing, wanted, dead, etc.
Table 5.3 Certificate Attributes
Attribute Name In CR In PR Description
officer name ✔    
number ✔    
date ✔    
place ✔    
type ✔    
Table 5.4 Union Attributes
Attribute Name In CR In PR Description
date of union ✔    
place of union ✔    
conjoint1 UIN ✔    
conjoint2 UIN ✔    
date of divorce ✔    
Table 5.5 Filiation Attributes
Attribute Name In CR In PR Description
parent1 UIN ✔    
parent2 UIN ✔    
Table 5.6 Document Type
Document Type Description
birth certificate To be completed
death certificate To be completed
marriage certificate To be completed

5.3. UIN Management

See UIN Management for the technical details of this interface.

5.3.1. Services

createUIN(attributes)

Generate a new UIN.

Authorization: To be defined

Parameters:attributes (list[(str,str)]) – A list of pair (attribute name, value) that can be used to allocate a new UIN
Returns:a new UIN or an error if the generation is not possible

This service is synchronous.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "PR" as PR participant "UIN Generator" as UIN note over CR,UIN: CR can request a new UIN CR -> UIN: createUIN([attributes]) UIN -->> CR: UIN note over PR,UIN: PR can request a new UIN PR -> UIN: createUIN([attributes]) UIN -->> PR: UIN

Fig. 5.7 createUIN Sequence Diagram

5.4. Biometrics

This interface is described biometric services in the context of an identity system. It is based on the following principles:

  • It supports only multi-encounter model, meaning that an identity can have multiple set of biometric data, one for each encounter.
  • It does not expose templates (only images) for CRUD services, with one exception to support the use case of documents with biometrics.
  • Images can be passed by value or reference. When passed by value, they are base64-encoded.
  • Existing standards are used whenever possible, for instance image preferred format is ISO-19794.

Note

Synchronous and Asynchronous Processing

Some services can be very slow depending on the algorithm used, the system workload, etc. Services are described so that:

  • If possible, the answer is provided synchronously in the response of the service.
  • If not possible for some reason, a status PENDING is returned and the answer, when available, is pushed to a callback provided by the client.

If no callback is provided, this indicates that the client wants a synchronous answer, whatever the time it takes.

If a callback is provided, the server will decide if the processing is done synchronously or asynchronously.

See Biometrics for the technical details of this interface.

5.4.1. Services

insert(subjectID, encounterID, galleryID, biographicData, contextualData, biometricData, clientData, callback, options)

Insert a new encounter. No identify is performed. This service is synchronous.

Authorization: To be defined

Parameters:
  • subjectID (str) – The subject ID
  • encounterID (str) – The encounter ID. This is optional
  • galleryID (list(str)) – the gallery ID to which this encounter belongs
  • biographicData (dict) – The biographic data (ex: name, date of birth, gender, etc.)
  • contextualData (dict) – The contextual data (ex: encounter date, location, etc.)
  • biometricData (list) – the biometric data (images)
  • clientData (bytes) – additional data not interpreted by the server but stored as is and returned when encounter data is requested.
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority, algorithm.
Returns:

a status indicating success, error, or pending operation. In case of success, the subject ID and the encounter ID are returned. In case of pending operation, the result will be sent later.
read(subjectID, encounterID, callback, options)

Retrieve the data of an encounter.

Authorization: To be defined

Parameters:
  • subjectID (str) – The subject ID
  • encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the subject are returned.
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority.
Returns:

a status indicating success, error, or pending operation. In case of success, the encounter data is returned. In case of pending operation, the result will be sent later.
update(subjectID, encounterID, galleryID, biographicData, contextualData, biometricData, callback, options)

Update an encounter.

Authorization: To be defined

Parameters:
  • subjectID (str) – The subject ID
  • encounterID (str) – The encounter ID
  • galleryID (list(str)) – the gallery ID to which this encounter belongs
  • biographicData (dict) – The biographic data (ex: name, date of birth, gender, etc.)
  • contextualData (dict) – The contextual data (ex: encounter date, location, etc.)
  • biometricData (list) – the biometric data (images)
  • clientData (bytes) – additional data not interpreted by the server but stored as is and returned when encounter data is requested.
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority, algorithm.
Returns:

a status indicating success, error, or pending operation. In case of success, the subject ID and the encounter ID are returned. In case of pending operation, the result will be sent later.
delete(subjectID, encounterID, callback, options)

Delete an encounter.

Authorization: To be defined

Parameters:
  • subjectID (str) – The subject ID
  • encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the subject are deleted.
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority.
Returns:

a status indicating success, error, or pending operation. In case of pending operation, the operation status will be sent later.
getTemplate(subjectID, encounterID, biometricType, biometricSubType, callback, options)

Retrieve the data of an encounter.

Authorization: To be defined

Parameters:
  • subjectID (str) – The subject ID
  • encounterID (str) – The encounter ID. This is optional. If not provided, all the encounters of the subject are returned.
  • biometricType (str) – The type of biometrics to consider
  • biometricSubType (str) – The subtype of biometrics to consider
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority.
Returns:

a status indicating success, error, or pending operation. In case of success, a list of template data is returned. In case of pending operation, the result will be sent later.
identify(galleryID, filter, biometricData, callback, options)

Identify a subject using biometrics data and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: To be defined

Parameters:
  • galleryID (str) – Search only in this gallery.
  • filter (dict) – The input data (filters and biometric data)
  • biometricData – the biometric data.
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority, maxNbCand, threshold, accuracyLevel.
Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.
identify(galleryID, filter, subjectID, callback, options)

Identify a subject using biometrics data of a subject existing in the system and filters on biographic or contextual data. This may include multiple operations, including manual operations.

Authorization: To be defined

Parameters:
  • galleryID (str) – Search only in this gallery.
  • filter (dict) – The input data (filters and biometric data)
  • subjectID – the subject ID
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority, maxNbCand, threshold, accuracyLevel.
Returns:

a status indicating success, error, or pending operation. A list of candidates is returned, either synchronously or using the callback.
verify(galleryID, subjectID, biometricData, callback, options)

Verify an identity using biometrics data.

Authorization: To be defined

Parameters:
  • galleryID (str) – Search only in this gallery. If the subject does not belong to this gallery, an error is returned.
  • subjectID (str) – The subject ID
  • biometricData – The biometric data
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority, threshold, accuracyLevel.
Returns:

a status indicating success, error, or pending operation. A status (boolean) is returned, either synchronously or using the callback. Optionally, details about the matching result can be provided like the score per biometric and per encounter.
verify(biometricData1, biometricData2, callback, options)

Verify that two sets of biometrics data correspond to the same subject.

Authorization: To be defined

Parameters:
  • biometricData1 – The first set of biometric data
  • biometricData2 – The second set of biometric data
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority, threshold, accuracyLevel.
Returns:

a status indicating success, error, or pending operation. A status (boolean) is returned, either synchronously or using the callback. Optionally, details about the matching result can be provided like the score per the biometric.
getGalleries(callback, options)

Get the ID os all the galleries.

Authorization: To be defined

Parameters:
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority.
Returns:

a status indicating success, error, or pending operation. A list of gallery ID is returned, either synchronously or using the callback.
getGalleryContent(galleryID, callback, options)

Get the content of one gallery, i.e. the IDs of all the records linked to this gallery.

Authorization: To be defined

Parameters:
  • galleryID (str) – Gallery whose content will be returned.
  • callback – The address of a service to be called when the result is available.
  • options (dict) – the processing options. Supported options are transactionID, priority.
Returns:

a status indicating success, error, or pending operation. A list of subjects/encounters is returned, either synchronously or using the callback.

5.4.2. Options

Table 5.7 Biometric Services Options
Name Description
transactionID A string provided by the client application to identity the request being submitted. It is optional in most cases. When provided, it can be used for tracing and debugging. It is mandatory for asynchronous services and is included in the response pushed asynchronously.
priority Priority of the request. Values range from 0 to 9
maxNbCand The maximum number of candidates to return.
threshold The threshold to apply on the score to filter the candidates during an identification, authentication or verification.
algorithm Specify the type of algorithm to be used.
accuracyLevel Specify the accuracy expected of the request. This is to support different use cases, when different behavior of the ABIS is expected (response time, accuracy, consolidation/fusion, etc.).

5.4.3. Data Model

Table 5.8 Biometric Data Model
Type Description Example
Gallery A group of subjects related by a common purpose, designation, or status. A subject can belong to multiple galleries. TBD
Subject Person who is known to an identity assurance system. TBD
Encounter Event in which the client application interacts with a subject resulting in data being collected during or about the encounter. An encounter is characterized by an identifier and a type (also called purpose in some context). TBD
Biographic Data a dictionary (list of names and values) giving the biographic data of interest for the biometric services. TBD
Filters a dictionary (list of names and values or range of values) describing the filters during a search. Filters can apply on biographic data, contextual data or encounter type. TBD
Biometric Data Digital representation of biometric characteristics. As an example, a record containing the image of a finger is a biometric data. All images can be passed by value (image buffer is in the request) or by reference (the address of the image is in the request). All images are compliant with ISO 19794. ISO 19794 allows multiple encoding and supports additional metadata specific to fingerprint, palmprint, portrait or iris. TBD
Candidate Information about a candidate found during an identification TBD
CandidateScore Detailed information about a candidate found during an identification. It includes the score for the biometrics used. TBD
Template A computed buffer corresponding to a biometric and allowing the comparison of biometrics. A template has a format that can be a standard format or a vendor-specific format. N/A

!include "skin.iwsd" class Gallery { string galleryID; } class Subject { string subjectID; } Subject "*" - "*" Gallery class Encounter { string encounterID; string encounterType; byte[] clientData; } Subject o-- "*" Encounter class BiographicData { string field1; int field2; date field3; ... } Encounter o- BiographicData class ContextualData { string field1; int field2; date field3; ... } ContextualData -o Encounter class Filters { string filter1; int filter2Min; int filter2Max; date filter3Min; date filter3Max; ... } class BiometricData { } Encounter o-- "*" BiometricData class Template { byte[] buffer; string format; } class Finger { byte[] fingerImage; URL fingerImageRef; } BiometricData <|-- Finger class Palm { byte[] palmImage; URL palmImageRef; } BiometricData <|-- Palm class Portrait { byte[] portraitImage; URL portraitImageRef; } BiometricData <|-- Portrait class Iris { byte[] irisImage; URL irisImageRef; } BiometricData <|-- Iris Finger -- Template Palm -- Template Portrait -- Template Iris -- Template class Candidate { int rank; int score; } Candidate . Subject class CandidateScore { int score; string encounterID; enum biometricType; enum biometricSubType; } Candidate -- "*" CandidateScore

Fig. 5.8 Biometric Data Model

5.5. Document Services

To be defined

5.6. Third Party Services

5.6.1. Services

verifyIdentity(UIN[, IDAttribute])

Verify Identity based on UIN and set of Identity Attributes. Attributes can be Biometric data, Civil data or a credential.

Authorization: To be defined

Parameters:
  • UIN (str) – The person’s UIN
  • IDAttribute (list[str]) – A list of list of pair (name,value) requested
Returns:

Y or N

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

identify([inIDAttribute][, outIDAttribute])

Identify a person based on a set of inIDAttribute Identity Attributes. Attributes can be Biometric data, Civil data or a credential. Returns list of identities with attributes specified in outIDAttribute

Authorization: To be defined

Parameters:
  • inIDAttribute (list[str]) – A list of list of pair (name,value) requested
  • outIDAttribute (list[str]) – A list of list of attribute names requested
Returns:

Y or N

In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

getAttributes(UIN, names)

Retrieve person attributes.

Authorization: To be defined

Parameters:
  • UIN (str) – The person’s UIN
  • names (list[str]) – The names of the attributes requested
Returns:

a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error
getAttributeSet(UIN, setName)

Retrieve person attributes corresponding to a predefined set name.

Authorization: To be defined

Parameters:
  • UIN (str) – The person’s UIN
  • setName (str) – The name of predefined attributes set name
Returns:

a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error